home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / DDJMAG / DDJ9310.ZIP / ALLHELP.ZIP / HELPSPEC.TXT < prev    next >
Text File  |  1993-09-13  |  9KB  |  223 lines
  1. WinHelp File Format -- Additional Internal Files
  2. ------------------------------------------------
  3.  
  4. The September 1993 and October 1993 issues of Dr. Dobb's Journal
  5. contain (in the "Undocumented Corner") a detailed description by Pete
  6. Davis of the WinHelp file format, used in the Windows .HLP and .MVB
  7. files.  Unfortunately, for space reasons only a limited number
  8. (though hopefully the most important) of the internal files that make
  9. up a .HLP file were discussed.
  10.  
  11. All internal files are shown in WHSTRUCT.H and in HELPDUMP.C.  Here
  12. are detailed descriptions of the internal files not discussed in
  13. the article.  This probably won't make much sense if you haven't
  14. read the two-part DDJ article.
  15.  
  16.  
  17. |FONT
  18. -----
  19.  
  20.     The |FONT file has three parts: a header, a list of available
  21. fonts, and a list of font descriptors.
  22.  
  23.     Following the file header for the |FONT file, is the FONTHEADER
  24. (see WHSTRUCT.H) record.  This is a 4 word field. The first word is
  25. the number of fonts available to the help file. The second word is
  26. the number of font descriptors actually used in the help file. The
  27. third is the default font descriptor and the last is the offset to
  28. the descriptors list.
  29.  
  30.     Immediately following the FONTHEADER is a list of font names. These are 
  31. all 20 character fixed length records. Each font name is null terminated so
  32. font names can be up to 19 characters long.
  33.  
  34.     Immediately following the fonts is the descriptor list. The font
  35. descriptors are individual instances of fonts that are actually used. For
  36. example, if you use 10 pt Helvetica, then a descriptor is created for that.
  37. If later you use 12 pt Helvetica, or Bold 10 pt Helvetica, different 
  38. descriptors are created. Different descriptors are created for the following:
  39.  
  40. 1) Using a different font
  41. 2) Using a different point size
  42. 3) Using a different attribute (Bold, Underline, Italics, etc)
  43. 4) Using a different color
  44.  
  45.     The first byte of the Font Descriptor is the attribute. This has
  46. attributes like Underline, Bold, etc. 
  47.  
  48.     The second byte is the size of the font in half points. Therefore
  49. an 8 pt font has a halfpoint size of 0x10. The third byte is the
  50. family of the font.
  51.  
  52.     The fourth byte is the name of the font. This is the index into
  53. the font list preceding the font descriptor list.
  54.  
  55.     The last 6 bytes are the colors for foreground and background.
  56. Actually, the background color is just a guess. Changing these values
  57. has no affect on the font as WinHelp displays it. I'm guessing it was
  58. a planned enhancement.
  59.  
  60.  
  61. |CONTEXT Hash values
  62.  
  63.     The |CONTEXT file contains hash values for all the keywords and
  64. context strings. This makes it easy to search on keywords and context
  65. strings. Simply calculate the hash value of the string and search
  66. the |CONTEXT file for a matching hash value. 
  67.  
  68.     Since the hash values can't be reversed, I have included a simple
  69. program called MAKEHASH.C. This will simply take a string from the
  70. command-line and convert it to a hash value. The hash algorithm uses
  71. a conversion table to remove case-sensitivity and reduce the number
  72. of characters involved in the hash. 
  73.  
  74. /********************************************
  75.   MakeHash.C
  76.   Pete Davis 
  77.   Calculates and outputs the hash value
  78. of a string. These hash values are used in
  79. the |CONTEXT file of a WinHelp .HLP file.
  80. *********************************************/
  81.  
  82. #include <stdio.h>
  83.  
  84.    char  MapTable[256];
  85.  
  86. /* Function prototypes */
  87. void BuildMap(void);
  88. long Hash (char *);
  89.  
  90. /********************************************
  91.   Builds character set map for hash function.
  92. *********************************************/
  93. void BuildMap() {
  94.    char c;
  95.    int  counter;
  96.  
  97.    /* Map A-Z and a-z as 0-25. */
  98.    for (counter = 'A', c = 17; counter <= 'Z'; counter++, c++) 
  99.       MapTable[counter] = MapTable[counter + 32] = c;
  100.    for (counter = '1', c = 1; counter <= '9'; counter++, c++) 
  101.       MapTable[counter] = c;
  102.    MapTable['0'] = 0x0A;
  103.    MapTable['.'] = 0x0C;
  104.    MapTable['_'] = 0x0D;
  105. }
  106.  
  107. /********************************************
  108.    Hash function by Ron Burk
  109. *********************************************/
  110. long Hash (char *p) {
  111.    long h = 0;
  112.    while(*p) {
  113.       char c = MapTable[*p++];
  114.       h = h * 0x2B + c;
  115.    }
  116.    return h;
  117. }
  118.  
  119. void main(int argc, char *argv[]) {
  120.   long HashVal;
  121.   BuildMap();
  122.   HashVal = Hash(argv[1]);
  123.   printf(" Hash value = %ld\n", HashVal);
  124. }
  125.  
  126. |KWMAP, |KWBTREE, and |KWDATA
  127.  
  128.     These three files are used together to get the keywords and their
  129. offsets to topics. These are the default keyword files. The default
  130. letter associated with Keywords in WinHelp is 'K'. Using the MULTIKEY
  131. option in the .HPJ file, though, you can have multiple keyword files
  132. based on different letters. If, for example, if you use the
  133. MULTIKEY=V option, you will have |VWMAP, |VWBTREE, and |VWDATA files
  134. associated with the 'V' keywords.
  135.  
  136.     We're going to stick with the 'K' keywords in our discussion and
  137. these are the only ones handled by the HELPDUMP program. The other
  138. keyword files are handled in exactly the same was as the 'K'
  139. keywords, so everything here applies.
  140.  
  141.     The |KWMAP file is the simplest. It starts with a single long
  142. that gives the number of KWMAPREC records. This is followed by a list
  143. of KWMAPREC records (See WHSTRUCT.H). The FirstRec field is the first
  144. keyword to appear on the given leaf page. The PageNum field,
  145. therefore, is the page number associated with the keywords. For
  146. example, if you have 3 leaf pages in the |KWBTREE file, then there
  147. will be 3 KWMAPREC records in |KWMAP. If there are, say, 60 keywords
  148. on page 0, 45 keywords on page 1, and 52 keywords on page 2, then the
  149. three records in |KWMAP would look like the ones in Figure 1.
  150.  
  151. ------------- Figure 1 ----------------
  152.  
  153.          |  Rec 1  |  Rec 2  |  Rec 3
  154. ---------+----------------------------
  155. FirstRec |     0   |    60   |   105
  156. Page Num |     0   |     1   |     2
  157.  
  158.     The |KWBTREE file has a list of all the keywords in the help
  159. file. Each keyword has a count and an offset associated with it. The
  160. count is the number of occurrences of the keyword in the help file.
  161. The offset is relative to the the beginning |KWDATA file.
  162.  
  163.     If you have a keyword with a count of 3 and an offset of 16
  164. (decimal), then you would go to the 16th byte of the |KWDATA file.
  165. You would then read the next 3 longs. Each of these longs would be an
  166. offset to the location in the |TOPIC file to find the occurance of
  167. the keyword.
  168.  
  169.     The way WinHelp uses is this information is as follows. When you
  170. select the "Search" button, you are given a list of keywords. If you
  171. double-click on a keyword, the all the topics with occurances of that
  172. keyword are listed.  The topic titles are actually pulled from the
  173. |TTLBTREE file which has the topics and offsets. You would simply
  174. match thes offset from |KWDATA with the offsets in |TTLBTREE to get
  175. the topic titles.
  176.  
  177. |CONTEXT
  178.  
  179.     The |CONTEXT file is a b-tree like the |TTLBTREE and |KWBTREE. It
  180. uses 2k page sizes and the same structure for the header, index
  181. nodes, and leaf nodes.
  182.  
  183.     The |CONTEXT file's data is simply a list of CONTEXTRECs which
  184. consist of a hash value and a topic offset (see WHSTRUCT.H).
  185.  
  186.     The hash values are for context strings used in the help file.
  187. The context strings are basically the hot links in the text. I
  188. question the need for this table since each context string, in the
  189. text, has the hash value. It would have been easier to just have the
  190. Topic offset associated with the hot-links instead of the hash value.
  191. You don't even have to actually calculate the hash value because it
  192. is provided with the hot-link itself.
  193.  
  194. |CTXOMAP
  195.  
  196.     In the .HPJ file you can set up context-sensitive points in your
  197. help file by adding a section titled [MAP]. Under the [MAP] section
  198. you list Topic Titles and assign unique IDs to each one. A sample
  199. [MAP] section could look like this:
  200.  
  201. [MAP]
  202. TableOfContents   0x0010
  203. Introduction      0x0020
  204. Chapter1          0x0030
  205. Chapter2          0x0040
  206. ...
  207. Chapter10         0x0120
  208. Glossary          0x0130
  209.  
  210.     You can then use these numbers in the WinHelp API function to
  211. jump to a specific topic. This information is listed in the |CTXOMAP
  212. file. The first WORD of the file is the number of entries in the
  213. Context Map table.
  214.  
  215.     This is followed by the individual CTXOMAPREC records (See
  216. WHSTRUCT.H).  The CTXOMAP records simply have the unique ID provided
  217. in the [MAP] section followed by the offset to the topic specified.
  218.  
  219. -- Pete Davis, September 1993
  220.    CIS 71644,3570
  221.    WPJ BBS 703-503-3021
  222.  
  223.